--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
docs/meshchatx_on_raspberry_pi.md v4.6.2-rc.1 (6ba4fecd) Text, 6.07 KB
Tc9d1d9# MeshChatX on Raspberry Pi
This guide shows a simple headless setup for running MeshChatX on a Raspberry Pi 4
with a web UI you can access from another device on your network.
This install path uses a release wheel, which already includes frontend assets.
Tc9d1d9## Automated Setup Scripts
Ta5d6ff```Ta5d6ffbash
curl -fsSL Ta5d6ff'https://raw.githubusercontent.com/Quad4-Software/MeshChatX/refs/heads/master/scripts/rpi/install_meshchatx.sh' Tb4b4b4| bash
Ta5d6ff```
If you have the repo cloned locally already:
Ta5d6ff```Ta5d6ffbash
bash scripts/rpi/install_meshchatx.sh
Ta5d6ff```
The installer guides you through:
Tff7b72- Optional Ta5d6ff`espeak-ng` install (tries apt/dnf/pacman)
Tff7b72- Install method (Ta5d6ff`pipx` or Ta5d6ff`venv + pip`)
Tff7b72- Wheel choice (latest stable, latest pre-release, or a custom URL)
Tff7b72- Optional **cosign** attestation: if a Ta5d6ff`*.whl.cosign.bundle` is published
next to the wheel, you can verify it. The script uses Ta5d6ff`cosign` on Ta5d6ff`PATH` if
present, or downloads a **checksum-verified** official Linux binary to Ta5d6ff`/tmp`
(the Sigstore bundle format is not reimplemented in shell; you still use the
real Ta5d6ff`cosign` to verify, without installing a distro package)
Tff7b72- Storage and Reticulum directories
Tff7b72- Bind host and port (with availability check)
Tff7b72- HTTPS on/off (default on)
Tff7b72- Service mode (Ta5d6ff`system`, Ta5d6ff`user`, or Ta5d6ff`none`)
Tff7b72- Service startup validation via the HTTP status endpoint
If startup validation fails, it prints recent logs and stops the service to avoid
restart loops.
Tc9d1d9## 1) Install Base Dependencies
Ta5d6ff```Ta5d6ffbash
sudo apt update
sudo apt upgrade -y
sudo apt install -y python3 python3-pip pipx
Ta5d6ff```
Tc9d1d9## 2) Enable pipx Path
Ta5d6ff```Ta5d6ffbash
pipx ensurepath
Tffa657source ~/.profile
Ta5d6ff```
If Ta5d6ff`pipx` is not available in your distro package repo, install it with:
Ta5d6ff```Ta5d6ffbash
python3 -m pip install --user pipx
python3 -m pipx ensurepath
Tffa657source ~/.profile
Ta5d6ff```
Tc9d1d9## 3) Install MeshChatX with pipx (recommended)
Preferred option (recommended): install from a release wheel (4.6.2 or newer),
because the wheel bundles frontend assets.
Ta5d6ff```Ta5d6ffbash
pipx install /path/to/reticulum_meshchatx-<version>-py3-none-any.whl
Ta5d6ff```
Direct example (v4.6.2):
Ta5d6ff```Ta5d6ffbash
pipx install Ta5d6ff"https://github.com/Quad4-Software/MeshChatX/releases/download/v4.6.2/reticulum_meshchatx-4.6.2-py3-none-any.whl"
Ta5d6ff```
Ta5d6ff`py3-none-any` wheels are architecture-independent, so the same wheel artifact
works on Raspberry Pi ARM and x86_64 Linux systems.
Upgrade example:
Ta5d6ff```Ta5d6ffbash
pipx upgrade meshchatx
Ta5d6ff```
Tc9d1d9## 4) Install MeshChatX without pipx (venv + pip)
If you prefer not to use pipx:
Ta5d6ff```Ta5d6ffbash
mkdir -p ~/meshchatx
Tffa657cd ~/meshchatx
python3 -m venv .venv
Tffa657source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install Ta5d6ff"https://github.com/Quad4-Software/MeshChatX/releases/download/v4.6.2/reticulum_meshchatx-4.6.2-py3-none-any.whl"
Ta5d6ff```
Run command in venv mode:
Ta5d6ff```Ta5d6ffbash
~/meshchatx/.venv/bin/meshchatx --headless --host T79c0ff0.0.0.0 --port T79c0ff8000
Ta5d6ff```
Tc9d1d9## 5) Run MeshChatX (Headless)
Ta5d6ff```Ta5d6ffbash
meshchatx --headless --host T79c0ff0.0.0.0 --port T79c0ff8000
Ta5d6ff```
Then open:
Ta5d6ff```Ta5d6ffbash
http://<pi-ip>:8000
Ta5d6ff```
Tc9d1d9## 6) Configure a systemd Service
Ta5d6ff`systemd` keeps MeshChatX running in the background and starts it automatically
on boot.
You have two service styles:
Tff7b72- System service (Ta5d6ff`/etc/systemd/system/...`) for always-on host services.
Tff7b72- User service (Ta5d6ff`~/.config/systemd/user/...`) for per-user sessions.
Tc9d1d9### Option A: System service (recommended for Pi node/server use)
Create Ta5d6ff`/etc/systemd/system/meshchatx.service`:
Ta5d6ff```Ta5d6ffini
Tff7b72[Unit]
Te6edf3DescriptionTff7b72=Ta5d6ffMeshChatX Headless (system service)
Te6edf3AfterTff7b72=Ta5d6ffnetwork-online.target
Te6edf3WantsTff7b72=Ta5d6ffnetwork-online.target
Tff7b72[Service]
Te6edf3TypeTff7b72=Ta5d6ffsimple
Te6edf3UserTff7b72=Ta5d6ffpi
Te6edf3GroupTff7b72=Ta5d6ffpi
Te6edf3WorkingDirectoryTff7b72=Ta5d6ff/home/pi/meshchatx
Te6edf3EnvironmentTff7b72=Ta5d6ff"Ta5d6ffPATH=/home/pi/.local/bin:/usr/bin:/binTa5d6ff"
Te6edf3ExecStartTff7b72=Ta5d6ff/home/pi/.local/bin/meshchatx --headless --host 0.0.0.0 --port 8000 --storage-dir /home/pi/meshchatx/storage --reticulum-config-dir /home/pi/.reticulum
Te6edf3RestartTff7b72=Ta5d6ffalways
Te6edf3RestartSecTff7b72=Ta5d6ff3
Tff7b72[Install]
Te6edf3WantedByTff7b72=Ta5d6ffmulti-user.target
Ta5d6ff```
The above service file is for pipx installs. For venv installs, use:
Ta5d6ff```Ta5d6ffini
Tff7b72[Service]
Te6edf3TypeTff7b72=Ta5d6ffsimple
Te6edf3UserTff7b72=Ta5d6ffpi
Te6edf3GroupTff7b72=Ta5d6ffpi
Te6edf3WorkingDirectoryTff7b72=Ta5d6ff/home/pi/meshchatx
Te6edf3EnvironmentTff7b72=Ta5d6ff"Ta5d6ffPATH=/home/pi/meshchatx/.venv/bin:/usr/bin:/binTa5d6ff"
Te6edf3ExecStartTff7b72=Ta5d6ff/home/pi/meshchatx/.venv/bin/meshchatx --headless --host 0.0.0.0 --port 8000 --storage-dir /home/pi/meshchatx/storage --reticulum-config-dir /home/pi/.reticulum
Te6edf3RestartTff7b72=Ta5d6ffalways
Te6edf3RestartSecTff7b72=Ta5d6ff3
Ta5d6ff```
Update Ta5d6ff`User`, Ta5d6ff`Group`, and paths if your install location is different.
Enable and start:
Ta5d6ff```Ta5d6ffbash
mkdir -p /home/pi/meshchatx/storage /home/pi/.reticulum
sudo chown -R pi:pi /home/pi/meshchatx
sudo systemctl daemon-reload
sudo systemctl Tffa657enable --now meshchatx.service
sudo systemctl status meshchatx.service
Ta5d6ff```
Tc9d1d9### Option B: User service (no sudo system unit)
Create Ta5d6ff`~/.config/systemd/user/meshchatx.service`:
Ta5d6ff```Ta5d6ffini
Tff7b72[Unit]
Te6edf3DescriptionTff7b72=Ta5d6ffMeshChatX Headless (user service)
Te6edf3AfterTff7b72=Ta5d6ffnetwork-online.target
Tff7b72[Service]
Te6edf3TypeTff7b72=Ta5d6ffsimple
Te6edf3WorkingDirectoryTff7b72=Ta5d6ff%h/meshchatx
Te6edf3EnvironmentTff7b72=Ta5d6ff"Ta5d6ffPATH=%h/.local/bin:/usr/bin:/binTa5d6ff"
Te6edf3ExecStartTff7b72=Ta5d6ff%h/.local/bin/meshchatx --headless --host 0.0.0.0 --port 8000 --storage-dir %h/meshchatx/storage --reticulum-config-dir %h/.reticulum
Te6edf3RestartTff7b72=Ta5d6ffalways
Te6edf3RestartSecTff7b72=Ta5d6ff3
Tff7b72[Install]
Te6edf3WantedByTff7b72=Ta5d6ffdefault.target
Ta5d6ff```
Enable/start user service:
Ta5d6ff```Ta5d6ffbash
systemctl --user daemon-reload
systemctl --user Tffa657enable --now meshchatx.service
systemctl --user status meshchatx.service
Ta5d6ff```
If you want user services to stay active without login:
Ta5d6ff```Ta5d6ffbash
sudo loginctl enable-linger pi
Ta5d6ff```
Tc9d1d9### Service management commands
Ta5d6ff```Ta5d6ffbash
sudo systemctl restart meshchatx.service
sudo systemctl stop meshchatx.service
sudo systemctl disable meshchatx.service
Ta5d6ff```
Useful logs and troubleshooting:
Ta5d6ff```Ta5d6ffbash
journalctl -u meshchatx.service -f
journalctl -u meshchatx.service -n T79c0ff200 --no-pager
systemctl show meshchatx.service -p ExecStart -p User -p Group
Ta5d6ff```
Tc9d1d9## Notes
Tff7b72- Reticulum configuration and identity data are stored in the service user's home
directory by default (for example Ta5d6ff`~/.reticulum` and MeshChatX storage paths).
Tff7b72- If you attach RNode hardware by USB, make sure the service user has permission
to access serial devices (Ta5d6ff`dialout` group on Debian-based systems).
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────